Skip to content

docs: show a custom input provider for Flow.ask() - #8809

Open
Felix Shi (shi-felix) wants to merge 3 commits into
crewAIInc:mainfrom
shi-felix:docs/flow-ask-input-provider
Open

Felix Shi (shi-felix) wants to merge 3 commits into
crewAIInc:mainfrom
shi-felix:docs/flow-ask-input-provider

Conversation

@shi-felix

@shi-felix Felix Shi (shi-felix) commented Oct 30, 2026 •

Copy link
Copy Markdown

Summary

Flow.ask() has an InputProvider extension point, but the guides never showed it, so the only documented way to answer a question was the console. This adds a runnable scripted provider — and exposes the flow.input_history API that the issue points at, which did not actually exist on main.

Fixes #8071.

The input_history gap

conversation.py documents Flow.input_history and input_provider.py says response metadata is
"stored in _input_history", but Flow only has the private _input_history attribute —
flow.input_history raises AttributeError. The example needs to inspect response metadata, so this
PR adds a read-only property that returns a copy of the private list. It adds no new abstraction and
does not change how entries are recorded.

Changes

  • lib/crewai/src/crewai/flow/runtime/__init__.py: an input_history property next to state/method_outputs, returning list(self._input_history) so callers cannot mutate the record.
  • docs/edge/en/concepts/flows.mdx: a new "Collecting Input with ask()" section with the complete scripted_input.py, the run command, expected output, the request/response metadata round trip, the None (no input available) path, and how ask() differs from handle_turn().
  • docs/edge/{ar,ko,pt-BR}/concepts/flows.mdx: the same section in each locale.
  • docs/edge/{en,ar,ko,pt-BR}/guides/flows/conversational-flows.mdx: a one-paragraph cross-link from the conversational guide to the new section.
  • lib/crewai/tests/test_flow_ask.py: a test for the public property (including that it returns a copy), and TestDocumentedScriptedProviderExample, which runs the documented flow and asserts the metadata round trip and the unavailable-input path.

Testing

python -m pytest lib/crewai/tests/test_flow_ask.py
50 passed in 28.84s

The documented script prints exactly what the guide claims:

topic: CrewAI
no further input available, using the fallback
result: CrewAI / (none)
What topic should we research? -> CrewAI | {'source': 'script', 'prompt': 'What topic should we research?'}
Anything else? -> None | None

ruff check on the touched file reports one F401 (typing.Literal unused, line 3923) that also
fails on unmodified main; I left it alone to keep this diff focused.

Python 3.13.14 on Windows. No credentials, no stdin, no model calls.

AI assistance

Written with AI assistance (WorkBuddy) and reviewed before submission.


Note

Low Risk
Documentation and a read-only accessor with copy semantics; no change to how ask() records input or to conversational turn APIs.

Overview
Documents custom input providers for Flow.ask() and closes a small API gap so the new guide can show metadata and audit trails.

Runtime: Adds a read-only flow.input_history property that returns a copy of the existing _input_history list (same fields as before: message, response, method name, timestamps, request/response metadata). Recording behavior is unchanged; callers no longer need to touch the private attribute.

Docs: New “Collecting Input with ask()” section in English, Arabic, Korean, and pt-BR concepts/flows pages — scripted InputResponse provider, None when no input, input_history inspection, and ask() vs handle_turn(). Conversational flows guides in those locales get a short cross-link when a question belongs inside one step.

Tests: Asserts input_history matches internal records and is immutable via copy, plus a test that runs the documented SurveyFlow / ScriptedProvider example.

Reviewed by Cursor Bugbot for commit 2dd221a. Bugbot is set up for automated code reviews on this repo. Configure here.

@mintlify

mintlify Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 5fc20aa.

Approve preview

@strix-security

strix-security Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Strix Security Review

Warning

This pull request has 117 commits after the last Strix review (84a8749). Strix has not reviewed these changes.
Automatic review on push is off for this repository. To review the latest changes, tag @strix-security in a comment, or turn on re-review on push.

✅ No open security findings.

PR summary: This PR adds documentation for `Flow.ask()` input providers across four locales and exposes a read-only `Flow.input_history` property returning a copy of the existing private `_input_history` list, plus tests for both the property and the documented example.

Review summary

No security issues found. The diff makes one functional change and it reduces exposure rather than adding it: the GraphQL query now receives playground_id and the PermissionsPolicy editor schema only loads secret names when scoping applies. Edge cases were checked (null scope, domain matching, wildcard matching, safe-character regex, IDOR via playgroundId) and either are pre-existing/handled server-side or unchanged by this PR.

Review 1 on this PR · 84a8749 · requested Oct 30 06:03 UTC when the PR was opened


Reviewed by Strix
Re-run review · Configure security review settings

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[docs] Demonstrate a custom input provider for Flow.ask()

1 participant